<!DOCTYPE html
  PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- saved from url=(0014)about:internet -->
<html xmlns:MSHelp="http://www.microsoft.com/MSHelp/" lang="en-us" xml:lang="en-us"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<meta name="DC.Type" content="topic">
<meta name="DC.Title" content="concurrent_vector">
<meta name="DC.subject" content="concurrent_vector">
<meta name="keywords" content="concurrent_vector">
<meta name="DC.Relation" scheme="URI" content="../tbb_userguide/Containers.htm">
<meta name="DC.Relation" scheme="URI" content="../tbb_userguide/Advanced_Idiom_Waiting_on_an_Element.htm">
<meta name="DC.Format" content="XHTML">
<meta name="DC.Identifier" content="tutorial_concurrent_vector">
<link rel="stylesheet" type="text/css" href="../intel_css_styles.css">
<title>concurrent_vector</title>
<xml>
<MSHelp:Attr Name="DocSet" Value="Intel"></MSHelp:Attr>
<MSHelp:Attr Name="Locale" Value="kbEnglish"></MSHelp:Attr>
<MSHelp:Attr Name="TopicType" Value="kbReference"></MSHelp:Attr>
</xml>
</head>
<body id="tutorial_concurrent_vector">
 <!-- ==============(Start:NavScript)================= -->
 <script src="..\NavScript.js" language="JavaScript1.2" type="text/javascript"></script>
 <script language="JavaScript1.2" type="text/javascript">WriteNavLink(1);</script>
 <!-- ==============(End:NavScript)================= -->
<a name="tutorial_concurrent_vector"><!-- --></a>

 
  <h1 class="topictitle1">concurrent_vector</h1>
 
  
  <div>
	 <p><samp class="codeph">A concurrent_vector&lt;<var>T</var>&gt;</samp> is a
		dynamically growable array of 
		<var>T</var>. It is safe to grow a 
		<samp class="codeph">concurrent_vector</samp> while other threads are also operating
		on elements of it, or even growing it themselves. For safe concurrent growing, 
		<samp class="codeph">concurrent_vector</samp> has three methods that support common
		uses of dynamic arrays: 
		<samp class="codeph">push_back</samp>, 
		<samp class="codeph">grow_by</samp>, and 
		<samp class="codeph">grow_to_at_least</samp>. 
	 </p>

	 <p>Method 
		<samp class="codeph">push_back(<var>x</var>)</samp> safely appends x to the
		array. Method 
		<samp class="codeph">grow_by(<var>n</var>)</samp> safely appends 
		<samp class="codeph"><var>n</var></samp> consecutive elements initialized
		with 
		<samp class="codeph"><var>T</var>()</samp>. Both methods return an iterator
		pointing to the first appended element. Each element is initialized with 
		<samp class="codeph"><var>T</var>()</samp>. So for example, the following
		routine safely appends a C string to a shared vector:
	 </p>

<pre>void Append( concurrent_vector&lt;char&gt;&amp; vector, const char* string ) {
    size_t n = strlen(string)+1;
    std::copy( string, string+n, vector.grow_by(n) );
}</pre>
	 <p>The related method 
		<samp class="codeph">grow_to_at_least(<var>n</var>)</samp>grows a vector to
		size 
		<var>n</var> if it is shorter. Concurrent calls to the growth
		methods do not necessarily return in the order that elements are appended to
		the vector.
	 </p>

	 <p>Method 
		<samp class="codeph">size()</samp> returns the number of elements in the vector,
		which may include elements that are still undergoing concurrent construction by
		methods 
		<samp class="codeph">push_back</samp>, 
		<samp class="codeph">grow_by,</samp> or 
		<samp class="codeph">grow_to_at_least</samp>. The example uses 
	 <span class="option">std::copy</span> and iterators, not 
	 <samp class="codeph">strcpy and pointers</samp>, because elements in a 
	 <samp class="codeph">concurrent_vector</samp> might not be at consecutive addresses.
	 It is safe to use the iterators while the 
	 <samp class="codeph">concurrent_vector</samp> is being grown, as long as the iterators
	 never go past the current value of 
	 <samp class="codeph">end()</samp>. However, the iterator may reference an element
	 undergoing concurrent construction. You must synchronize construction and
	 access.
	 </p>

	 <p>A 
		<samp class="codeph">concurrent_vector&lt;<var>T</var>&gt;</samp> never
		moves an element until the array is cleared, which can be an advantage over the
		STL 
	 <span class="option">std::vector</span> even for single-threaded code. However, 
	 <samp class="codeph">concurrent_vector</samp> does have more overhead than 
	 <span class="option">std::vector</span>. Use 
	 <samp class="codeph">concurrent_vector</samp> only if you really need the ability to
	 dynamically resize it while other accesses are (or might be) in flight, or
	 require that an element never move.
	 </p>

	 <div class="Note"><h3 class="NoteTipHead">
					Caution</h3>
		<p>Operations on 
		  <samp class="codeph">concurrent_vector</samp> are concurrency safe with respect to
		  
		  <em>growing</em>, not for clearing or destroying a vector. Never invoke
		  method 
		  <samp class="codeph">clear()</samp> if there are other operations in flight on the
		  
		  <samp class="codeph">concurrent_vector</samp>.
		</p>

	 </div>
  </div>


<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong>&nbsp;<a href="../tbb_userguide/Containers.htm">Containers</a></div>
</div>
<div>
<ul class="ullinks">
<li class="ulchildlink"><a href="../tbb_userguide/Advanced_Idiom_Waiting_on_an_Element.htm">Advanced Idiom: Waiting on an Element</a><br>
</li>
</ul>
</div>

</body>
</html>
